/*
 * ClientNetworkManager.java
 *    Author: nfk
 *      Date: Sep 19, 2008
 *      
 *   I'faces:
 *      ClientNetworkManager
 */

package at.syncme.framework.midp;


import java.io.IOException;


/**
 * An interface which extends NetworkManager with some client-specific methods.
 * @author nfk
 */
public interface ClientNetworkManager extends NetworkManager {

    /**
     * Connects to the specified device/service/server with given ID on the cached list.
     * @param id entry ID of the connection (starting at 0)
     * @return if connection attempt was successful
     * @throws IllegalArgumentException if id < 0
     * @throws IOException if any network error occurs
     * @throws IllegalStateException if client is already connected
     */
    public boolean connect(final int id) throws IOException;


    /**
     * Returns if the client is connected.
     * @return if the client is connected
     */
    public boolean isConnected();


    /**
     * Returns if the client was previously connected.
     * @return if the client was previously connected
     */
    public boolean hasPreviousConnection();


    /**
     * Reconnects the previously disconnected / broken connection.
     * @return if reconnection attempt was successful
     * @throws IOException if any network error occurs
     * @throws IllegalStateException if client is already connected
     * @throws UnsupportedOperationException if no previous connection is known
     */
    public boolean reconnect() throws IOException;


    /**
     * Discovers devices which offer a game server. These targets are saved sequentially and may be connected
     * to by specifing the ID of the entry only. Will return cached entries; if there are none, it starts a
     * new discovery.
     * @return list of found devices/services/servers; null if none were found
     * @throws IOException if device discovery failed
     */
    public String[] discover() throws IOException;


    /**
     * Discovers devices which offer a game server. These targets are saved sequentially and may be connected
     * to by specifing the ID of the entry only. Allows forcing of new discovery; behaves like the
     * parameterless method if false is passed.
     * @param nocache force new discovery / disallow returning cache
     * @return list of found devices/services/servers; null if none were found
     * @throws IOException if device discovery failed
     */
    public String[] discover(final boolean nocache) throws IOException;


    /**
     * Creates a new thread which listens for new lines and forwards them to the set EventListener.
     * @throws IllegalStateException if no input stream is available, listener is unset or already receiving
     */
    public void startReceival();

}

/* End of ClientNetworkManager.java */
